Doc: Application Backend Blueprint

September 23, 2025 by Trying to Sleep 😥

Describe basic blueprint of spring boot backend application. Explain basic roles, documentation, project structure and the security #Programming

Pengembangan REST API Untuk Web Application Menggunakan Spring Boot

Konsep pengembangan REST API dengan Spring Boot berfokus pada kemudahan, kecepatan, dan konvensi di atas konfigurasi untuk membangun layanan web yang tangguh. Spring Boot, sebagai bagian dari ekosistem Spring Framework, menyederhanakan proses ini dengan menghilangkan banyak boilerplate code (kode berulang) dan menyediakan konfigurasi otomatis.

Berikut adalah konsep-konsep utama dalam pengembangan REST API menggunakan Spring Boot:

Representational State Transfer (REST)

Sebelum masuk ke Spring Boot, penting untuk memahami prinsip-prinsip REST itu sendiri:

Akses Sumber Daya (Resources): API berpusat pada sumber daya (misalnya, pengguna, produk). Setiap sumber daya diidentifikasi oleh Uniform Resource Identifier (URI) yang unik.
Metode HTTP: Interaksi dengan sumber daya dilakukan menggunakan metode HTTP standar, seperti:
- GET: Mengambil (retrieve) data sumber daya.
- POST: Membuat (create) sumber daya baru.
- PUT: Memperbarui (update) sumber daya yang sudah ada.
- DELETE: Menghapus (delete) sumber daya.
Nir-status (Stateless): Setiap permintaan dari klien ke server harus berisi semua informasi yang diperlukan untuk memproses permintaan tersebut. Server tidak menyimpan data sesi klien di antara permintaan.
Representasi: Data dikirimkan dalam format tertentu, biasanya JSON atau XML. JSON adalah format yang paling umum digunakan karena lebih ringan dan mudah diurai.

Anotasi Inti Spring Boot

Spring Boot menggunakan anotasi untuk memetakan permintaan HTTP ke metode dalam kelas Java.

@RestController: Anotasi ini menggabungkan @Controller dan @ResponseBody, menandakan bahwa kelas ini adalah controller RESTful yang akan mengembalikan data sebagai respons HTTP, bukan nama view. Ini sangat menyederhanakan pengembangan API.
@RequestMapping: Digunakan untuk memetakan permintaan web ke metode handler tertentu. Anda juga bisa menggunakan varian yang lebih spesifik seperti @GetMapping, @PostMapping, @PutMapping, dan @DeleteMapping untuk kejelasan yang lebih baik.
@RequestBody: Mengikat parameter metode dengan badan permintaan HTTP (biasanya data JSON).
@PathVariable: Mengikat parameter metode dengan bagian variabel dari URI.
@RequestParam: Mengikat parameter metode dengan parameter kueri URL.

Struktur Proyek

Pengembangan dengan Spring Boot biasanya mengikuti struktur proyek standar:

Kontroler (Controller): Kelas yang menangani permintaan HTTP masuk dan mengembalikan respons.
Layanan (Service): Kelas yang berisi logika bisnis. Kelas ini bertindak sebagai perantara antara controller dan repository, memisahkan logika bisnis dari lapisan web.
Repositori (Repository): Kelas yang menangani operasi data (misalnya, berinteraksi dengan basis data).
Model (Model)/Entitas (Entity): Kelas Java yang merepresentasikan struktur data.

Dependency Management

Spring Boot menggunakan Maven atau Gradle untuk mengelola dependensi. Dengan adanya Spring Initializr, dapat dengan cepat membuat proyek baru dan memilih dependensi yang dibutuhkan, seperti spring-boot-starter-web untuk pengembangan REST API.

**Konfigurasi Otomatis (Auto-configuration)**

Salah satu fitur utama Spring Boot adalah konfigurasi otomatis. Spring Boot akan secara otomatis mengkonfigurasi aplikasi berdasarkan dependensi yang ada di classpath. Misalnya, jika menambahkan dependensi spring-boot-starter-web, Spring Boot akan otomatis mengkonfigurasi server web tertanam (seperti Tomcat).

Embedded Server

Spring Boot menyertakan server web tertanam (seperti Tomcat, Jetty, atau Undertow), yang memungkinkan menjalankan aplikasi Java sebagai file .jar yang dapat dieksekusi sendiri tanpa perlu menyebarkannya (deploy) ke server aplikasi terpisah.

Keamanan

Spring Boot memudahkan integrasi keamanan dengan menambahkan dependensi Spring Security. Ini memungkinkan untuk mengamankan REST API dengan fitur-fitur seperti otentikasi dan otorisasi, dengan kombinasi konsep-konsep ini, Spring Boot menyediakan kerangka kerja yang kuat dan efisien untuk membangun REST API yang siap produksi dengan kode yang minimal.

---

Project Base Guidance

Struktur project backend pada umumnya memiliki beberapa ketentuan dasar:

Struktur project menggunakan "Feature-Based Structure" dimana struktur package dikelompokan berdasarkan fitur
Struktur project menggunakan "Function-Based Structure" dimana struktur package dikelompokan berdasarkan fungsinya masing-masing
Framework database management menggunakan JPA untuk memudahkan pengelolaan koneksi ke database
Hindari nested logical, gunakan "Early Exit Clauses Programming"

Nested logical

if (logic A) {
  if (logic B) {
    if (logic C) {
      run allowed logic
      ...
      ...
    } else {
      return;
    }
  } else {
    return;
  }
} else {
  return;
}

Early exit clauses

if (!logic A) return;
if (!logic B) return;
if (!logic C) return;

run allowed logic
...
...

Pastikan untuk menambahkan log pada proses2 utama untuk memudahkan dalam proses troubleshoot jika terdapat kendala

public void onFunctionA(String param) {
  log.info("Function A - start with param {}", param);

  if (!logic A) {
    log.warn("Function A - invalid logic A");
    return;
  }

  run allowed logic
  ...
  ...
  log.info("Function A - success execute flow with result {}", result);
}

Lengkapi controller dengan dokumentasi untuk memudahkan proses development dari sisi client (frontend) - biasanya menggunakan swagger

---

Documentation

Java => https://openjdk.org/projects/jdk/24/
Springboot => https://spring.io/blog/2025/09/18/spring-boot-3-5-6-available-now
JWT => https://www.jwt.io/introduction#what-is-json-web-token
JPA => https://spring.io/projects/spring-data-jpa
Lombok => https://projectlombok.org/
Swagger => API Documentation & Design Tools for Teams | Swagger

---

Src: lokasi main project

Base: package untuk simpan base function yang akan dipakai pada main project, misal untuk simpan config, constant, enum, base model, base service dll
- Annotations: package untuk simpan lokasi custom constant, bisa digunakan untuk membuat annotation untuk lakukan validasi dsb. Untuk saat ini custom annotation yang dibuat untuk lakukan validasi controller ketika terdapat request masuk, akan di intercept untuk dilakukan validasi apakan request yang masuk merupakan request yang valid
- Configurations: package untuk menampung beberapa konfigurasi yang digunakan, misal konfigurasi untuk mengatur data source koneksi ke database, konfigurasi terkait dokumentasi, konfigurasi terkait security dll
- Constants: package untuk tampung file2 constant, misal kumpulan error message
- Enums: package untuk tampung file2 enum, yang digunakan untuk tampung nilai2 yang sejenis yang dirangkum sebagai suatu object
- Models: package untuk menampung custom model yang bersifat reusable dan tidak ada keterkaitan langsung dengan model pada fitur utama, contoh: BaseResponseModel untuk standarisasi REST response
- Utils: package untuk menampung custom tools untuk membantu proses di main feature menjadi lebih sederhana, misal buat base service untuk melakukan transformasi object ke bentuk json, transformasi object date ke format tanggal tertentu
Common: package untuk menampung kumpulan REST API yang digunakan secara umum dan tidak terkait langsung dengan maun feature, misal REST API untuk proses login, dimana terdiri dari beberapa sub package:
- controllers
- dtos
- entities
- repositories
- services
Feature: package dengan kumpulan subpackage yang merepresentasikan main feature, dimana subpackage nya sendiri memiliki struktur sub-subpackage berikut:
- feature-package
  - controllers
  - dtos
  - entities
  - repositories
  - services
Resources: package untuk tampung properti aplikasi dan aset lainnya

---

Project Security

Untuk security dibagi menjadi 2 bagian, public security dan private security

Public security hanya digunakan untuk proses login, request cukup menyertakan public key didalam request header saat call service login, kemudian terdapat proses verifikasi kredensial, dan jika data login valid maka akan generate access token yang akan digunakan untuk request API selanjutnya

Private security digunakan disetiap request API selain login, dimana saat melakukan request harus menyertakan access token kedalam request header.

Proses validasi access token dibagi kedalam beberapa step:

- Validasi request header harus menyertakan access token
- Validasi value dari access token harus valid dimana akan melakukan validasi terhadap:
  - format access token
  - claims access token harus valid sesuai dengan signature
  - expired access token
- Validasi function access, dimana terdapat proses validasi apakah user yang melakukan request berhak mengakses function tersebut

Access token menggunakan JWT (JSON Web Token), dimana didalam JWT terdapat beberapa informasi dasar yang digunakan untuk proses validasi setiap ada request masuk seperti:

email
role
group
expired date token

Saat login user akan menggunakan auth Basic (panggil PublicSecurityAnnotation) dan saat user akses API dari mai feature, akan menggunakan auth Bearer (panggil PrivateSecurityAnnotation)

---